home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / language / gemfst18.lzh / GEMFINST.DOC < prev    next >
Text File  |  1992-12-06  |  15KB  |  595 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.                                     GemFast v1.8
  29.  
  30.                         Public Domain GEM Programming Library
  31.                                     By Ian Lepore
  32.          
  33.         
  34.                          Installation and Portability Notes
  35.         
  36.         
  37.         
  38.         
  39.         
  40.         
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.        Contents
  72.  
  73.        Packing List  . . . . . . . . . . . . . . . . . . . . . . . . .  - 1 -
  74.  
  75.        Installation and Usage Instructions . . . . . . . . . . . . . .  - 2 -
  76.           Basic installation . . . . . . . . . . . . . . . . . . . . .  - 2 -
  77.           LD.TTP Installation (for HSC users)  . . . . . . . . . . . .  - 3 -
  78.           Usage  . . . . . . . . . . . . . . . . . . . . . . . . . . .  - 3 -
  79.           IMPORTANT RECOMPILE WARNING! . . . . . . . . . . . . . . . .  - 3 -
  80.  
  81.        GemFast System Overview . . . . . . . . . . . . . . . . . . . .  - 5 -
  82.           The GEMFAST.H header file  . . . . . . . . . . . . . . . . .  - 5 -
  83.           The AESFAST.A library  . . . . . . . . . . . . . . . . . . .  - 5 -
  84.           The VDIFAST.A library  . . . . . . . . . . . . . . . . . . .  - 5 -
  85.           Stack and memory usage . . . . . . . . . . . . . . . . . . .  - 6 -
  86.           GEM and supervisor mode  . . . . . . . . . . . . . . . . . .  - 6 -
  87.  
  88.        Portability Notes . . . . . . . . . . . . . . . . . . . . . . .  - 7 -
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.                                         - i -
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.        Packing List
  138.  
  139.  
  140.             GemFast v1.8 is distributed in 3 archive files, as follows:
  141.  
  142.                  GEMFST18.LZH -  Libraries, headers, and documentation.
  143.                  GEMFSC18.LZH -  Library source code.
  144.                  GEMFXM18.LZH -  Example application source code.
  145.  
  146.             The GEMFST18.LZH archive contains the following files:
  147.  
  148.                  AESFAST.A    -  The AES library.
  149.                  VDIFAST.A    -  The VDI library.
  150.                  GEMFAST.H    -  GEM programming header file.
  151.                  EXTERROR.H   -  Extended error message header file.
  152.                  GEMFAST.DOC  -  The library reference manual.
  153.                  GEMFINST.DOC -  This document.
  154.                  AESVRSN.DOC  -  Revision history for AES library.
  155.                  VDIVRSN.DOC  -  Revision history for VDI library.
  156.                  LD.TTP       -  New linker, required for HSC users.
  157.  
  158.             The GEMFSC18.LZH archive contains two other archives, which in
  159.             turn contain many files.  (It compresses much tighter this way.)
  160.             When unpacked, the following directory structure emerges:
  161.  
  162.                  VDIBIND\     -  All VDI library functions.
  163.                  AESBIND\     -  Low-level AES bindings.
  164.                  AESXBIND.S\  -  Extended bindings (ASM code).
  165.                  AESXBIND.C\  -  Extended bindings (C code).
  166.                  AESUTIL.S\   -  Low-level utilities (ASM code).
  167.                  AESUTIL.C\   -  Low-level utilities (C code).
  168.                  AESFUNCS\    -  The bulk of the high-level code.
  169.                  INCLUDE\     -  Header files.
  170.  
  171.             The GEMFXM18.LZH archive contains the following files:
  172.  
  173.                  (need a list here)
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                         - 1 -
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.        Installation and Usage Instructions
  204.  
  205.  
  206.             These installation instructions assume you are using GemFast with
  207.             a DRI-compatible compiler, and are using GemFast as your primary
  208.             GEM bindings system.  Compatible compilers are:
  209.  
  210.                  Sozobon C v1.x and v2.0
  211.                  Heat and Serve C (HSC) v1.34 or higher
  212.                  Laser / MegaMax C
  213.                  Alcyon C
  214.  
  215.             The distributed libraries are NOT compatible with other
  216.             compilers.  If your compiler is not on the above list, please
  217.             proceed to the Portability Notes chapter.
  218.  
  219.  
  220.        Basic installation
  221.  
  222.  
  223.             Installation of GemFast is fairly simple.  Copy the VDIFAST.A and
  224.             AESFAST.A files to the directory your compiler uses for
  225.             libraries.  If you use ALN or another indexed linker, be sure to
  226.             run DOINDEX to build new library index files.  Copy the GEMFAST.H
  227.             and EXTERROR.H files to the directory your compiler uses for
  228.             header files.  Put the documentation wherever you want.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.                                         - 2 -
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.        LD.TTP Installation (for HSC users)
  270.  
  271.  
  272.             If you're using Heat-and-Serve C v1.3x, you need to copy LD.TTP
  273.             to replace your current version.  Older versions of LD had some
  274.             compiled-in limits on the number of object files in a library. 
  275.             There are now so many modules in the GemFast libraries that these
  276.             limits get exceeded.  The new LD has larger default limits, and
  277.             also some new command line options that let you increase the
  278.             limits for any given run.  The new command line options are:
  279.  
  280.                  -lo####     The number of object files referenced/used.
  281.                  -lm####     The number of object files skipped/unused.
  282.                  -ls####     The number of non-local symbols.
  283.  
  284.             The default limits are 300 used object modules, 400 unused
  285.             modules from libraries (modules skipped during multipass
  286.             processing), and 1000 non-local symbols.  To double these limits,
  287.             add the following to your LD command line:
  288.  
  289.                  -lo600 -lm800 -ls2000
  290.  
  291.             The numbers you specify must be between 1 and 32767 inclusive. 
  292.             The larger the numbers, the more memory is needed at runtime.
  293.  
  294.  
  295.        Usage
  296.  
  297.  
  298.             To link your programs with the GemFast libraries, just include
  299.             the library names on the linker command line.  Example:
  300.  
  301.                  cc myprog.c aesfast.a vdifast.a dlibs.a
  302.  
  303.             There is now a linker order dependancy!  Many of the new high-
  304.             level functions require VDI services, so you must now place
  305.             VDIFAST.A after AESFAST.A on your linker command line.  The
  306.             libraries are still internally sequenced so that your linker will
  307.             only need to make one pass of each library.  Also, some of the
  308.             new high-level dialogs require runtime library services such as
  309.             sprintf(), so it is best if the GemFast libraries appear before
  310.             your C runtime library.
  311.  
  312.             You can use any runtime startup module you want, when your
  313.             compiler/linker provide several startup modules.  Nothing in the
  314.             GemFast libraries relies on items in the startup files.
  315.  
  316.  
  317.        IMPORTANT RECOMPILE WARNING!
  318.  
  319.  
  320.             You MUST recompile all your existing GEM object modules as a part
  321.             of installing v1.8!  Because macros in GEMFAST.H remap some
  322.             standard GEM calls through new internal library routines, it is
  323.             imperative that all your GEM-related object code be recompiled
  324.             using the new GEMFAST.H header file before you link *anything*
  325.  
  326.                                         - 3 -
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.             with the new libraries.
  336.  
  337.             It is hard for me to overstate the importance of this. 
  338.             Everything will die horribly if you link an existing object
  339.             module containing GEM calls with the new libraries.
  340.  
  341.             Here's my suggestion:  Go look *everywhere* on all your
  342.             partitions or disks.  Nuke all object files that have even a
  343.             remote chance of containing a GEM call.  If you have your own
  344.             libraries that contain GEM calls, nuke the libraries.  Do all the
  345.             deletions at once, then go through and recompile things where
  346.             necessary.
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.                                         - 4 -
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.        GemFast System Overview
  402.  
  403.  
  404.             GemFast provides complete support for GEM programming.  It
  405.             provides the GEM support for the Sozobon and HSC public domain
  406.             compilers.  In addition, it replaces the existing GEM support for
  407.             the Laser, MegaMax, and Alcyon compiler